home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / DevCon / Atlanta_1990 / Atlanta-Devcon.2 / Libraries / Locale / locale.doc < prev    next >
Encoding:
Text File  |  1992-08-26  |  15.4 KB  |  544 lines
  1. /****** localisation.library/OpenCountryTable ****************************
  2.  
  3.     NAME
  4.     OpenTerritory -- open a territory table
  5.  
  6.     SYNOPSIS
  7.     territory = OpenTerritory(name)
  8.     D0                        A0
  9.  
  10.     FUNCTION
  11.     This function returns a pointer to a territory table that was
  12.     previously loaded in memory. If the territory table is not already
  13.     there it will be loaded in from disk. First the directory from
  14.     which the process was launched is searched, then the locale:
  15.     directory.
  16.  
  17.     INPUTS
  18.     name        a pointer to a null terminated string
  19.  
  20.     RESULTS
  21.     territory    a territory table pointer
  22.  
  23.     SEE ALSO
  24.     CloseTerritory, locale/locale.h
  25.  
  26.  
  27. /*************************************************************************
  28.  
  29.     NAME
  30.     OpenLanguage -- open a language table
  31.  
  32.     SYSNOPSIS
  33.         langauge = OpenLanguage(name)
  34.         D0                      A0
  35.  
  36.     FUNCTION
  37.     This function returns a pointer to a language table, if that table
  38.     has already been loaded in memory. If not, the directory from
  39.     which the calling process was launched is searched, then the
  40.     locale: directory.
  41.  
  42.     INPUT
  43.     name        a pointer to a null terminated string
  44.  
  45.     RESULTS
  46.     language    a language table pointer
  47.  
  48.     SEE ALSO
  49.     CloseLanguage, locale/locale.h
  50.  
  51.  
  52. /*************************************************************************
  53.  
  54.     NAME
  55.     CloseTerritory -- close a territory table
  56.  
  57.     SYNOPSIS
  58.     CloseTerritory(territory)
  59.                    A0
  60.     void CloseTerritory(struct territory *)
  61.  
  62.     FUNCTION
  63.     This function informs the system that access to the given territory
  64.     table has concluded. If the open count of the territory table
  65.     reaches zero, it is removed from memory unless its PERMANENT flag
  66.     is set.
  67.  
  68.     INPUTS
  69.     territory        a territory table pointer
  70.  
  71.     SEE ALSO
  72.     OpenTerritory, locale/locale.h
  73.  
  74.  
  75. /*************************************************************************
  76.  
  77.     NAME
  78.     CloseLanguage -- close a language table
  79.  
  80.     SYNOPSIS
  81.     CloseLanguage(language)
  82.                    A0
  83.     void CloseLanguage(struct language *)
  84.  
  85.     FUNCTION
  86.     This function informs the system that access to the given language
  87.     table has concluded. If the open count of the language table
  88.     reaches zero, it is removed from memory unless its PERMANENT flag
  89.     is set.
  90.  
  91.     INPUTS
  92.     language    a language table pointer
  93.  
  94.     SEE ALSO
  95.     OpenLanguage, locale/locale.h
  96.  
  97. /*************************************************************************
  98.  
  99.     NAME
  100.     DefaultTerritory -- return the default territory for system func.
  101.  
  102.     SYNOPSIS
  103.     territory = DefaultTerritory()
  104.  
  105.     struct Territory DefaultTerritory(void)
  106.  
  107.     FUNCTION
  108.     Returns the default territory used in DOS functions such as
  109.     DateToStr() and StrToDate(). The name of the territory file can
  110.     be determined from the territory->Node.ln_Name field.
  111.  
  112.     RESULTS
  113.     territory    a territory table pointer
  114.  
  115.     SEE ALSO
  116.     locale/locale.h
  117.  
  118.  
  119. /*************************************************************************
  120.  
  121.     NAME
  122.     DefaultLanguage -- return the default territory for system functions
  123.  
  124.     SYNOPSIS
  125.     language = DefaultLanguage()
  126.  
  127.     struct Language DefaultLanguage(void)
  128.  
  129.     FUNCTION
  130.     Returns the default language used in DOS functions such as
  131.     DateToStr() and StrToDate(). The name of the language directory,
  132.     and thus the langauge itself, can be determined from the
  133.     language->Node.ln_Name field.
  134.  
  135.     RESULTS
  136.     language    a language table pointer
  137.  
  138.     SEE ALSO
  139.     locale/locale.h
  140.  
  141.  
  142. /*************************************************************************
  143.  
  144.     NAME
  145.     CatOpen -- open a message catalogue
  146.  
  147.     SYNOPSIS
  148.     catalogue = CatOpen(name)
  149.     D0                  A0
  150.  
  151.     FUNCTION
  152.     This function returns a pointer to the named catalogue. If it is
  153.         not already in memory it will first search the directory from
  154.     which the translation was loaded, and finally the locale:
  155.     directory.
  156.  
  157.     If the name string contains a ":" character, the locale directory
  158.     is not searched anymore.
  159.  
  160.     INPUTS
  161.     name        a pointer to a null terminated string specifying a
  162.             catalogue.
  163.  
  164.     RESULTS
  165.     catalogue    a pointer to a message catalogue
  166.  
  167.     SEE ALSO
  168.     CatClose(), CatGets(), locale/locale.h
  169.  
  170.  
  171. /*************************************************************************
  172.  
  173.     NAME
  174.     CatGets -- get a message from a message catalogue
  175.  
  176.     SYNOPSIS
  177.     message = CatGets(catalogue,set,msgNum,defaultString)
  178.     D0                A0    D0  D1     A1
  179.     char *TranslateMsg(struct Catalogue *,int,int,char *);
  180.  
  181.     FUNCTION
  182.     This function returns a pointer to the message corresponding to the
  183.     given table and message number. Should the table be a NULL, this
  184.     function will return the default string given.
  185.  
  186.     INPUTS
  187.     table        a translation table
  188.         set        a set number, not implmented. Use 1 as set number.
  189.     msgNum        a message number
  190.  
  191.     RESULTS
  192.     message        a pointer to a null terminated string
  193.  
  194.     SEE ALSO
  195.     CatOpen(), CatClose(), locale/locale.h
  196.  
  197. /*************************************************************************
  198.  
  199.     NAME
  200.     CatClose -- close a message catalogue
  201.  
  202.     SYNOPSIS
  203.     CatClose(catalogue)
  204.              A0
  205.     void CatClose(struct Translation *);
  206.  
  207.     FUNCTION
  208.     This function informs the localisation library that access to the
  209.     given catalogue has been concluded. If the open count of the
  210.     catalogue reaches zero, it is removed from memory, unless it's
  211.     PERMANENT flag is set.
  212.  
  213.     INPUTS
  214.     catalogue    a pointer to a translation table
  215.  
  216.     SEE ALSO
  217.     CatOpen(), CatGets(), locale/locale.h
  218.  
  219. /*************************************************************************
  220.  
  221.     NAME
  222.     StrColl -- compare two strings according to collation information
  223.  
  224.     SYNOPSIS
  225.     result = StrCmp(string1,string2,language)
  226.         D0              A0      A1      A2
  227.     int StrCmp(char *, char *, struct Language *)
  228.  
  229.     FUNCTION
  230.     Compares string1 to string2 according to the collation information
  231.     provided in the language table and returns an integer greater than,
  232.     equal to, or less than zero, accordingly as the string pointed to
  233.     by string1 is greater than, equal to, or less than the string
  234.     pointed to by string2.
  235.  
  236.     INPUTS
  237.     string1        a pointer to a null terminated string
  238.     string2        a pointer to a null terminated string
  239.     language    a pointer to a language table
  240.  
  241.     RESULTS
  242.     result        relationship between string1 and string2
  243.  
  244.     SEE ALSO
  245.     locale/locale.h
  246.  
  247. /*************************************************************************
  248.  
  249.     NAME
  250.     StrXFrm -- transform string according to collation information
  251.  
  252.     SYNOPSIS
  253.     length = StrXFrm(string1,string2,size,language)
  254.     D0               A0      A1      D0   A2
  255.  
  256.     FUNCTION
  257.     This function transforms the string pointed to by string2 and
  258.     places the resulting string into the array pointed to by string1.
  259.     The transformation is such that if the strcmp function is applied
  260.     to two transformed strings, it returns a value corresponding to
  261.     the result returned by the StrColl() function applied to the two
  262.     original strings. No more than 'size' characters are placed into
  263.     the array pointed to by string1, including the terminating NULL
  264.     character. If 'size' is zero, string1 is permitted to be a NULL
  265.     pointer.
  266.  
  267.     INPUTS
  268.     string1        a pointer to a null terminated string
  269.     string2        a pointer to a null terminated string
  270.     size        maximum numer of characters to be put in string1
  271.     language    a pointer to a language table
  272.  
  273.     RESULTS
  274.     length        length of the transformed string. If 'length' is
  275.             greater than 'size', then string1[] is undetermined.
  276.  
  277.     SEE ALSO
  278.     StrColl(), locale/locale.h
  279.  
  280. /*************************************************************************
  281.  
  282.    NAME
  283.     RawDoFmt -- format data into a character stream.
  284.  
  285.    SYNOPSIS
  286.     RawDoFmt(FormatString, DataStream, PutChProc, PutChData);
  287.                  a0            a1          a2         a3
  288.  
  289.     void RawDoFmt(STRPTR,APTR,void (*)(),APTR);
  290.  
  291.    FUNCTION
  292.     perform "C"-language-like formatting of a data stream, outputting
  293.     the result a character at a time.  Where % formatting commands are
  294.     found in the FormatString, they will be replaced with the
  295.     corresponding element in the DataStream.  %% must be used in the
  296.     string if a % is desired in the output.
  297.  
  298.     Under V36, RawDoFmt() returns a pointer to the end of the DataStream
  299.     (The next argument that would have been processed).  This allows
  300.     multiple formatting passes to be made using the same data.
  301.  
  302.    INPUTS
  303.     FormatString - a "C"-language-like NULL terminated format string,
  304.     with the following supported % options:
  305.  
  306.      %[order$][flags][width.limit][length]type
  307.  
  308.     order  - argument number to use for this entry, followed by a "$".
  309.     flags  - only one allowed. '-' specifies left justification.
  310.     width  - field width.  If the first character is a '0', the
  311.          field will be padded with leading 0's.
  312.       .    - must follow the field width, if specified
  313.     limit  - maximum number of characters to output from a string.
  314.          (only valid for %s).
  315.     length - size of input data defaults to WORD for types d, x,
  316.          and c, 'l' changes this to long (32-bit).
  317.     type   - supported types are:
  318.             b - BSTR, data is 32-bit BPTR to byte count followed
  319.                 by a byte string, or NULL terminated byte string.
  320.                 A NULL BPTR is treated as an empty string.
  321.                 (Added in V36 exec)
  322.             d - decimal
  323.             x - hexadecimal
  324.             s - string, a 32-bit pointer to a NULL terminated
  325.                 byte string.  In V36, a NULL pointer is treated
  326.                 as an empty string
  327.             c - character
  328.  
  329.     DataStream - a stream of data that is interpreted according to
  330.          the format string.  Often this is a pointer into
  331.          the task's stack.
  332.     PutChProc  - the procedure to call with each character to be
  333.          output, called as:
  334.  
  335.     PutChProc(Char,  PutChData);
  336.           D0-0:8 A3
  337.  
  338.         the procedure is called with a NULL Char at the end of
  339.         the format string.
  340.  
  341.     PutChData - a value that is passed through to the PutChProc
  342.         procedure.  This is untouched by RawDoFmt, and may be
  343.         modified by the PutChProc.
  344.  
  345.    EXAMPLE
  346.     ;
  347.     ; Simple version of the C "sprintf" function.  Assumes C-style
  348.     ; stack-based function conventions.
  349.     ;
  350.     ;   long eyecount;
  351.     ;   eyecount=2;
  352.     ;   sprintf(string,"%s have %ld eyes.","Fish",eyecount);
  353.     ;
  354.     ; would produce "Fish have 2 eyes." in the string buffer.
  355.     ;
  356.         XDEF _sprintf
  357.         XREF _AbsExecBase
  358.         XREF _LVORawDoFmt
  359.     _sprintf:    ; ( ostring, format, {values} )
  360.         movem.l a2/a3/a6,-(sp)
  361.  
  362.         move.l    4*4(sp),a3       ;Get the output string pointer
  363.         move.l    5*4(sp),a0       ;Get the FormatString pointer
  364.         lea.l    6*4(sp),a1       ;Get the pointer to the DataStream
  365.         lea.l    stuffChar(pc),a2
  366.         move.l    _AbsExecBase,a6
  367.         jsr    _LVORawDoFmt(a6)
  368.  
  369.         movem.l (sp)+,a2/a3/a6
  370.         rts
  371.  
  372.     ;------ PutChProc function used by RawDoFmt -----------
  373.     stuffChar:
  374.         move.b    d0,(a3)+        ;Put data to output string
  375.         rts
  376.  
  377.    WARNING
  378.     This Amiga ROM function formats word values in the data stream.  If
  379.     your compiler defaults to longs, you must add an "l" to your
  380.     % specifications.  This can get strange for characters, which might
  381.     look like "%lc".
  382.  
  383.    SEE ALSO
  384.     Documentation on the C language "printf" call in any C language
  385.     reference book.
  386.  
  387.  
  388. ******* dos.library/DateToStr ************
  389. *
  390. *   NAME
  391. *    DateToStr -- Converts a DateStamp to a string
  392. *
  393. *   SYNOPSIS
  394. *    error = DateToStr(country,datetime)
  395. *    D0                A0      D1
  396. *    BOOL DateToStr(struct DateTime *)
  397. *
  398. *   FUNCTION
  399. *    StamptoStr converts an AmigaDOS DateStamp to a human
  400. *    readable ASCII string as requested by your settings in the
  401. *    DateTime structure.
  402. *
  403. *   INPUTS
  404. *    country - a pointer to a country table; used only with FORMAT_LOC.
  405. *
  406. *    DateTime - a pointer to an initialized DateTime structure.
  407. *
  408. *    The DateTime structure should be initialized as follows:
  409. *
  410. *    dat_Stamp - a copy of the datestamp you wish to convert to
  411. *          ascii.
  412. *
  413. *    dat_Format - a format    byte which specifies the format    of the
  414. *          dat_StrDate.    This can be any    of the following
  415. *          (note: If value used is something other than those
  416. *          below, the default of    FORMAT_DOS is used):
  417. *
  418. *          FORMAT_DOS:      AmigaDOS format (dd-mmm-yy).
  419. *
  420. *          FORMAT_INT:      International    format (yy-mmm-dd).
  421. *
  422. *          FORMAT_USA:      American format (mm-dd-yy).
  423. *
  424. *          FORMAT_CDN:      Canadian format (dd-mm-yy).
  425. *
  426. *          FORMAT_DEF:      The default format is used. If the localisation
  427. *                  library has not been opened yet FORMAT_DOS is
  428. *                  is used. Otherwise the default country table is
  429. *                  used.
  430. *
  431. *          FORMAT_LOC:      The country table specified is used for determining
  432. *                  the format, otherwise the country input is ignored.
  433. *
  434. *    dat_Flags - a    flags byte.  The only flag which affects this
  435. *          function is:
  436. *
  437. *          DTB_SUBST:      If set, a string such    as Today,
  438. *                  Monday, etc.,    will be    used instead
  439. *                  of the dat_Format specification if
  440. *                  possible.
  441. *          DTB_FUTURE:      Ignored by this function.
  442. *
  443. *    dat_StrDay - pointer to a buffer to receive the day of the
  444. *          week string.    (Monday, Tuesday, etc.). If null, this
  445. *          string will not be generated.
  446. *
  447. *    dat_StrDate -    pointer    to a buffer to receive the date
  448. *          string, in the format    requested by dat_Format,
  449. *          subject to possible modifications by DTB_SUBST.  If
  450. *          null,    this string will not be    generated.
  451. *
  452. *    dat_StrTime -    pointer    to a buffer to receive the time    of day
  453. *          string. If NULL, this    will not be generated.
  454. *
  455. *   RESULT
  456. *    error    - a non-zero return indicates that the DateStamp was
  457. *          invalid, and could not be converted.    Zero indicates
  458. *          that everything went according to plan.
  459. *
  460. *   SEE ALSO
  461. *    StrtoDate(), libraries/datetime.h
  462. *
  463.  
  464.  
  465. ******* dos.library/StrToDate ************
  466. *
  467. *   NAME
  468. *    StrToDate -- Converts a string to a DateStamp
  469. *
  470. *   SYNOPSIS
  471. *    error = StrToDate(country,datetime)
  472. *    D0                A0      D1
  473. *
  474. *    BOOL StrToDate( struct DateTime * )
  475. *
  476. *   FUNCTION
  477. *    Converts a human readable ASCII string into an AmigaDOS
  478. *    DateStamp.
  479. *
  480. *   INPUTS
  481. *    DateTime - a pointer to an initialized DateTime structure.
  482. *
  483. *    The DateTime structure should    be initialized as follows:
  484. *
  485. *    dat_Stamp  - ignored on input.
  486. *
  487. *    dat_Format - a format    byte which specifies the format    of the
  488. *        dat_StrDat.  This can    be any of the following    (note:
  489. *        If value used    is something other than    those below,
  490. *        the default of FORMAT_DOS is used):
  491. *
  492. *        FORMAT_DOS:      AmigaDOS format (dd-mmm-yy).
  493. *
  494. *        FORMAT_INT:      International    format (yy-mmm-dd).
  495. *
  496. *        FORMAT_USA:      American format (mm-dd-yy).
  497. *
  498. *        FORMAT_CDN:      Canadian format (dd-mm-yy).
  499. *
  500. *        FORMAT_DEF:      The default format is used. If the localisation
  501. *                  library has not been opened yet FORMAT_DOS is
  502. *                  is used. Otherwise the default country table is
  503. *                  used.
  504. *
  505. *        FORMAT_LOC:      The country table specified is used for determining
  506. *                  the format, otherwise the country input is ignored.
  507. *
  508. *    dat_Flags - a flags byte.  The only flag which affects this
  509. *        function is:
  510. *
  511. *        DTB_SUBST:      ignored by this function
  512. *
  513. *        DTB_FUTURE:      If set, indicates that strings such
  514. *                  as (stored in    dat_StrDate) "Monday"
  515. *                  refer    to "next" monday. Otherwise,
  516. *                  if clear, strings like "Monday"
  517. *                  refer    to "last" monday.
  518. *
  519. *    dat_StrDay - ignored bythis function.
  520. *
  521. *    dat_StrDate -    pointer    to valid string    representing the date.
  522. *          This can be a    "DTB_SUBST" style string such as
  523. *          "Today" "Tomorrow" "Monday", or it may be a string
  524. *          as specified by the dat_Format byte.    This will be
  525. *          converted to the ds_Days portion of the DateStamp.
  526. *          If this pointer is NULL, DateStamp->ds_Days will not
  527. *          be affected.
  528. *
  529. *    dat_StrTime -    Pointer    to a buffer which contains the time in
  530. *          the ASCII format hh:mm:ss.  This will    be converted
  531. *          to the ds_Minutes and    ds_Ticks portions of the
  532. *          DateStamp.  If this pointer is NULL, ds_Minutes and
  533. *          ds_Ticks will    be unchanged.
  534. *
  535. *   RESULT
  536. *    error    - a non-zero return indicates that a conversion    could
  537. *        not be performed. A Zero return indicates that the
  538. *        DateTime.dat_Stamp variable contains the converted
  539. *        values.
  540. *
  541. *   SEE ALSO
  542. *    DateToStr(), libraries/datetime.h
  543. *
  544.